<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>libnetconf: Data Validation</title>
<link href="../../tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../jquery.js"></script>
<script type="text/javascript" src="../../dynsections.js"></script>
<link href="../../navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../resize.js"></script>
<script type="text/javascript" src="../../navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="../../search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="../../search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="../../doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="../../libnetconf-logo.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">libnetconf
   &#160;<span id="projectnumber">0.10.0-146_trunk</span>
   </div>
   <div id="projectbrief">NETCONF Library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "../../search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="../../index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="../../pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="../../modules.html"><span>Modules</span></a></li>
      <li><a href="../../annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="../../files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="../../search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="../../search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('db/df0/validation.html','../../');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Data Validation </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a href="http://tools.ietf.org/html/rfc6241" title="RFC 6241">RFC 6241</a> defines NETCONF :validate capability intended to allow validation of the configuration data. This capability specifies new operation &lt;validate&gt; and adds &lt;test-option&gt; parameter to the &lt;edit-config&gt; operation.</p>
<p>On the client side, libnetconf allows to create &lt;validate&gt; RPC as well as to specify &lt;test-option&gt; of &lt;edit-config&gt; RPC. When the :validate capability is supported by the server, the default &lt;test-option&gt; value is test-then-set, so each &lt;edit-config&gt; change is validated.</p>
<p>On the server side, libnetconf performs data validation on <a class="el" href="../../d1/deb/datastores.html">datastore parts</a> that provides validators. libnetconf use Relax NG schema to validate syntax of the datastore content and Schematron to check semantics. Validators are loaded as a standalone files generated by <em>lnctool(1)</em>, which is part of libnetconf standard instalation.</p>
<p>libnetconf automatically searches for the validators during <a class="el" href="../../db/d67/group__store.html#ga69009c5985f9eec3a6920f98a6a1a5e6" title="Create a new datastore structure of the specified implementation type. ">ncds_new()</a> and <a class="el" href="../../d8/d55/group__transapi.html#ga80e69b4cada8c35e5e358287e8af3d85" title="Create new datastore structure with transaction API support. ">ncds_new_transapi()</a> calls. Validators are supposed to be placed in the same directory as data model provided to the mentioned function as its model_path parameter. Alternatively, validators can be connected with the datastore manually, using <a class="el" href="../../db/d67/group__store.html#ga4777c16043f5856c5a65bcd20b5ecc31" title="Set validators (or disable validation) on the specified datastore. ">ncds_set_validation()</a>. This function also allows to switch off validation on a specific datastore part.</p>
<h2>lnctool(1) Usage</h2>
<p>Complete list of <em>lnctool(1)</em>'s options can be displayed using -h option:</p>
<div class="fragment"><div class="line">$ lnctool -h</div>
</div><!-- fragment --><p><em>lnctool(1)</em> is used to perform the following 3 actions:</p>
<ol type="1">
<li><em>convert</em> - converts YANG model to the YIN format</li>
<li><em>validation</em> - generates validation files for a given YANG data model</li>
<li><em>transapi</em> - prepares a transAPI module template</li>
</ol>
<p>Each next action includes all the previous actions, so executing the <em>transapi</em> action generates also the YIN format of the data model and all the validation files. More information about using <em>lnctool(1)</em> for creating a transAPI modules can be found in the <a class="el" href="../../d9/d25/transapi.html">Transaction API (transAPI)</a> section. Here we focus on the <em>validation</em> action.</p>
<p>As the main input, you have to specify the main YANG data model of the datastore (<code>--model</code> option). If there are also some augmenting models, you should specify them as a parameter to the (multiple) <code>--augment-model</code> option(s). If you need some imported data models, specify the path where to search for them as the <code>--search-path</code> option.</p>
<p>Based on a YANG data model, <em>lnctool(1)</em> generates all necessary files needed by libnetconf. Basically, it generates YIN format of the data model required by <a class="el" href="../../db/d67/group__store.html#ga69009c5985f9eec3a6920f98a6a1a5e6" title="Create a new datastore structure of the specified implementation type. ">ncds_new()</a> and <a class="el" href="../../d8/d55/group__transapi.html#ga80e69b4cada8c35e5e358287e8af3d85" title="Create new datastore structure with transaction API support. ">ncds_new_transapi()</a> functions. If you use some extension models via <a class="el" href="../../db/d67/group__store.html#ga145c9446fad8c350934c21ca86cbaf47" title="Add an configuration data model to the internal list of models. Such model is used to resolve imports...">ncds_add_model()</a> or <a class="el" href="../../db/d67/group__store.html#ga93c65facb061f1048674343ac94a993b" title="Specify a directory path to the location where the required (imported or included) data models can be...">ncds_add_models_path()</a>, you have to specify also these models as <em>lnctool(1)</em>'s &lt;augment models&gt; parameter.</p>
<p>The following commands generate validation files for the NACM data model:</p>
<div class="fragment"><div class="line">$ cd libnetconf/models/</div>
<div class="line">$ lnctool --model ./ietf-netconf-acm.yang --output-dir ./nacm/ validation</div>
</div><!-- fragment --><p>The output directory <code>nacm/</code> now contains generated NACM data model in YIN format, Relax NG schemas and Schematron XSL stylesheet for validation.</p>
<p>Path to the search directory should be also specified in the server source code to allow libnetconf to find imported data model (<em>ietf-yang-types.yin</em> in this case).</p>
<dl class="section note"><dt>Note</dt><dd>Return value checks are skipped in this example for simplicity. Do not copy-paste this example. Also note, that NACM is one of internal libnetconf datastores and it is not needed to add it manually by <a class="el" href="../../db/d67/group__store.html#ga69009c5985f9eec3a6920f98a6a1a5e6" title="Create a new datastore structure of the specified implementation type. ">ncds_new()</a>. This is JUST a simple (stupid) example.</dd></dl>
<div class="fragment"><div class="line">ds = <a class="code" href="../../db/d67/group__store.html#ga69009c5985f9eec3a6920f98a6a1a5e6">ncds_new</a>(<a class="code" href="../../db/d67/group__store.html#ggab0f0cbd5268577ec36fc76cf89c72a8fad552454d25247a7a0f8d1ab875a1d629">NCDS_TYPE_FILE</a>, <span class="stringliteral">&quot;./models/nacm/ietf-netconf-acm.yin&quot;</span>, NULL);</div>
<div class="line"><a class="code" href="../../d0/d3b/group__fileds.html#gad48955dab497b1258d80019e542acb9b">ncds_file_set_path</a>(ds, ds_path);</div>
<div class="line"><a class="code" href="../../db/d67/group__store.html#gaabb1ae2c497726ad826fc6478f97e8ff">ncds_init</a>(ds);</div>
<div class="line"><a class="code" href="../../db/d67/group__store.html#ga93c65facb061f1048674343ac94a993b">ncds_add_models_path</a>(<span class="stringliteral">&quot;./models/&quot;</span>);</div>
<div class="line"><a class="code" href="../../db/d67/group__store.html#gab2a27448a52972db6807571590a5c6da">ncds_consolidate</a>();</div>
</div><!-- fragment --><p>If the validators files are stored in the same directory as a basic data model (<em>ietf-netconf-acm.yin</em> in this case), libnetconf automatically loads them during <a class="el" href="../../db/d67/group__store.html#ga69009c5985f9eec3a6920f98a6a1a5e6" title="Create a new datastore structure of the specified implementation type. ">ncds_new()</a> or <a class="el" href="../../d8/d55/group__transapi.html#ga80e69b4cada8c35e5e358287e8af3d85" title="Create new datastore structure with transaction API support. ">ncds_new_transapi()</a> calls. If you store the validators files somewhere else, <a class="el" href="../../db/d67/group__store.html#ga4777c16043f5856c5a65bcd20b5ecc31" title="Set validators (or disable validation) on the specified datastore. ">ncds_set_validation()</a> function can be used to specify their location:</p>
<div class="fragment"><div class="line"><a class="code" href="../../db/d67/group__store.html#ga4777c16043f5856c5a65bcd20b5ecc31">ncds_set_validation</a>(ds, 1, <span class="stringliteral">&quot;./models/nacm/ietf-netconf-acm-config.rng&quot;</span>, <span class="stringliteral">&quot;./models/nacm/ietf-netconf-acm-schematron.xsl&quot;</span>);</div>
</div><!-- fragment --><p>If validators files are not found or validation is switched off (via <a class="el" href="../../db/d67/group__store.html#ga4777c16043f5856c5a65bcd20b5ecc31" title="Set validators (or disable validation) on the specified datastore. ">ncds_set_validation()</a> with enable parameter set to 0), validation is not performed on such datastore part.</p>
<h3>Data Model Features</h3>
<p>When the data model includes some <code>feature</code> definition and corresponding <code>if-feature</code> statement(s), all such features are enabled for validation by default. If you want to enable only specific features (or disable all of them), you have to use the <em>lnctool(1)</em>'s <code>--feature</code> option. The option can be use multiple times and the given value has the following form:</p>
<div class="fragment"><div class="line">--feature module_name:feature_to_enable</div>
</div><!-- fragment --><p>If you want to disable all features of the module, use the following syntax:</p>
<div class="fragment"><div class="line">--feature module_name:</div>
</div><!-- fragment --><p>Remember that if you have some augmenting modules, you should also set features of those augmenting modules. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="../../da/d1b/usage.html">Using libnetconf</a></li>
    <li class="footer">Generated on Fri Apr 15 2016 09:20:09 for libnetconf by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="../../doxygen.png" alt="doxygen"/></a> 1.8.6 </li>
  </ul>
</div>
</body>
</html>
